@pwighton To avoid losing this to a reversion, please update https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors, as this page is auto-generated from a source during the release process.

Thanks @effigies, I just updated that page.

a template entity should not be introduced, but rather use the tpl entity?

Yes, good catch. I've reworked this so that it uses the tpl entity, and to clarify that one can either use the tpl entity, atlas entity, but not both.

I would suggest to keep the tpl entity added to the filename, so the file can be shared as a standalone entity. Alternatively, make it clear that the various atlases now belong to the space PS13 (i.e. add space-PS13)

I'm not sure I understand why it can't be shared as a standalone entity as is? Regarding space entity. I guess we should decide if space is REQUIRED when using atlas, or if it's only REQUIRED for disambuguaiton.

small typo in atlas. Is it clear from this that atlas belongs to the PS13 tpl and/or PS13 space?

Fixed.

space-fsaverage?

Actually I've removed these entierly. They've been replaced by atlas-fsaverage_dseg.nii.gz and atlas-fsaverage_dseg.json

tpl-ps13_space-fsaverage_dseg.nii.gz?

I'm not sure what the intent is here. This file has been lifted straight from FreeSurfer and, while used during PS13 processing (to generate results at the ROI-level) it has not been processed/modified by the PS13 pipeline.

The sub-01 part should remain in the filename, to indicate that it belongs to sub-01

I agree with Martin on this it's too easy to overwrite other subject specific files without the sub-<label> remaining. Was this changed to make the sharing of a single subject atlas/template consistent with a multi-subject atlas/template?

Reverted.

sub-01 should remain

reverted

this is neither an atlas or template at this stage, but still sub-01. When aggregating across subjects, this will be a tpl and atlas (for segmentation).

I think tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz is valid, given that the label entity is valid (https://bids-specification.readthedocs.io/en/stable/glossary.html#label-entities), which belongs to the template. I see the dseg parts as atlases.

Good point. I've reverted these changes.

This isn't germane to this PR, so let me know if I should move it to the discussion at bids-standard/bids-specification.

I like the result of this, but I started trying to write some it out in the schema last night and began re-evaluating my initial thoughts. I guess it follows the same sort of logic as a session entity, so sure.

@bendhouseart perhaps you are looking at the wrong place? This is an alternative to my alternative to the BEP. In my alternative, the schema is updated with the specs (or should be).

bids-standard#1856

We have not introduced atlas- yet, so this admonition feels too preemptive

1- Why moving from below? It feels more clear to me the current ordering of description (1- template, 2- space, 3- cohort, 4- atlas). The reason for that is, to me, the difference between template and space is the more subtle/finicky, then cohort is necessary for template and space, and finally atlas depends on the three of them.

2- template-<label> - you mean tpl-<label> ? If so, I don't see how atlas- can be used without tpl-.

Thanks for these changes, @oesteban, and let's have a meeting soon to discuss this further. @pwighton - please correct me if I am wrong, but I think @pwighton is arguing that an atlas is currently defined as being a segmentation (defined on a template), while tpl is a an averaged feature map (i.e. template) across subjects. Therefore, it may seem unintuitive to have both tpl- and atlas- in the filename, as it cannot both be a feature map and a segmentation? The space entity would reconcile how atlas- can be used without tpl-. But if tpl- serves the same role as space- then having tpl- and atlas- in the name still makes sense, but is then an atlas and not a template.

Yes, that was the understanding I arrived at later (#1 (comment)).

As I argue there, the data type (whether an average feature map or a segmentation) in BIDS is expressed by the suffix. This use of atlas- is just reflecting some suffixes, and leaving tpl- for others, which is counter-productive because we have suffix that fully expresses this (and conflicting with BIDS, which doesn't change sub- depending on the suffix).

I think the best way to approach this is through the homology/analogy between subject and template and between session and cohort. If we cannot agree on that mapping, hardly we're going to find a common place for atlas.

I think the best way to approach this is through the homology/analogy between subject and template and between session and cohort. If we cannot agree on that mapping, hardly we're going to find a common place for atlas.

I've raised this point previously, but dropped it because it didn't seem critical, but it looks like it will be. Cohort in the biological sciences generally means "a set of subjects who satisfy a set of inclusion criteria" and while this can be used to denote a session or timepoint, e.g. "subjects who have been imaged between Jan and Dec 2024", it can be used for other things as well, e.g "Subjects who were born before 1980" or "Subjects who have a BMI less than 20" or "Subjects who speak Italian".

Here are how some other controlled terminologies define cohort:

"In OHDSI research, we define a cohort as a set of persons who satisfy one or more inclusion criteria for a duration of time." 1

"A group of individuals who share a common exposure, experience or characteristic or a group of individuals followed-up or traced over time in a cohort study. [AMA Manual of Style]" 2

"Cohort Study: Observational study that assembles a large group of individuals, collects extensive information about
these people at baseline, and follows up with the group for a period of time in an attempt to examine
relationships between outcomes and risk factors." 3

Sure, the homology is scoped within BIDS:

tpl- works like sub- (and also provides a reference frame for the results within the folder tpl-/ like sub-/)
cohort- works like session- (and also provides a grouping mechanism within the corresponding folder)

beyond that, this mapping does not intend to make cohorts an equivalent to sessions.

How can this be removed? Perhaps what's missing is some more explicit bridge between individual subjects and group (template) specifications, but that doesn't mean that, when you are working with individual subjects you still use sub-[...] structures like the BIDS raw&derivatives specs.

Thanks for bringing this up, I feel you just made clear a blind spot in my way to think about templates and I really appreciate it :)

First as a note, please use semantic break lines following the rest of the specs, they are easier to read and review.

If I managed to understand the intent, then I think this phrasing would be more unambiguous:

@effigies please double check the above makes sense :)

I think defining where and at what time the averaging takes place is still tricky to define and make solid requirements for. For example, for PET data we usually 1) project the 4D PET to e.g. fsaverage (using anatomical data, i.e. sub-XX_space-fsaverage_pet.nii.gz), 2) smooth the data along the cortical surface, and then 3) perform kinetic modeling to produce binding estimates. We then average these binding estimates across subjects (i.e. sub becomes tpl to create a new template existing in fsaverage space). This process works well because it respects individual cortical boundaries by registering individual surfaces to fsaverage. It would instead be suboptimal to first volumetrically smooth each individual data in subject space, produce binding estimates, register all subjects to e.g. the first subject, average the binding estimates across subjects to produce a new template, and then register that template to e.g. fsaverage. But ultimately, the outcome of these two workflows would be the same i.e. average binding estimates across a set of subjects in fsaverage space. But in the first case, this might be considered an atlas on top of tpl-fsaverage (i.e. tpl-fsaverage_atlas-PET_pet.nii.gz) or a new template since we are averaging across subjects (i.e. tpl-PET_space-fsaverage_pet.nii.gz), whereas for the second case it might be considered a template in fsaverage space (i.e. tpl-PET_space-fsaverage_pet.nii.gz). Now if I define a novel PET parcellation/atlas based on this, I would have tpl-fsaverage_atlas-PET_probseg/dseg.nii.gz for case 1 (i.e. only the suffix datatype changes), and for case 2 it would be tpl-PET_space-fsaverage_atlas-PET_probseg/dseg.nii.gz.

In my humble opinion, I suggest that when averaging is taking place for a new datatype e.g. pet (instead of T1w) and a new set of subjects in either a new or already defined space, this becomes a new template existing in that defined space. A new segmentation/atlas may then subsequently be defined on top of this (with a dseg/probseg extension), and will therefore also belong to a specific template and a specific space.

Your example seems to me like pretty clearly belonging to tpl-fsaverage (and your second paragraph is consistent with the changes you made in bids-standard@891bcf0, which I was planning to respond in our meeting but then got distracted and did not mention.

HOWEVER, there was a point in the meeting where we touched base on this. What we said is, considering that, even though you are working in fsaverage coordinates you are not the original originator of fsaverage, then we should recommend that a new template identifier (such as PS13) is issued.

In the dataset_description.json then we should clearly indicate that the new template is in fact aligned with fsaverage. If that is the case, then sub-01_hemi-L_space-PS13_PET.gii becomes absolutely equivalent to sub-01_hemi-L_space-fsaverage_PET.gii, in both cases signifying PET data on a surface defined in fsaverage/PS13 space, which is the same.

We could (and I like the idea a lot) enforce that space is present in the filenames if the new template does not generate its own coordinate system (which is what @pwighton was basically pointing us at):

tpl-PS13/
    tpl-PS13_space-MNI152Lin_T1w.nii.gz

This example tells you that you generated a T1w average (whether in a custom space of the study or you moved everything to MNI152Lin should be found in some provenance metadata and/or a paper) that is not the one distributed with MNI152Lin, but in this case it is aligned with that space.

The generation of new template identifiers can be recommended in that case, but this has effects to things like TemplateFlow more than the specification itself. BIDS can perfectly live without this recommendation, nor the combination of tpl- and space- in this use-case.

Why?

• For BIDS, the specification disallowing generating new template identifiers if they are really defined in a different, existing template space, would work as-is. It tells you how to organize the data and the organization is absolutely valid.
• TemplateFlow and other potential services care about the ownership and access rights of stakeholders. At the moment, the developers of TemplateFlow regulate that, but, if it were a "proper" registry, we should not modify say fsaverage adding PS13 when the authors are not exactly the same or the scope of fsaverage is not to cover PS13.

That said, this is already creating difficulties in understanding, so I believe BIDS should observe these nuances and I think adding these mechanisms is a good thing for the spec. But again, it's more a problem of data ownership/access/stewardship than it is of nomenclature or organization.

Happy to work through examples in the call if necessary.

Thanks for this reply, @oesteban, and looking forward to work through some of the examples in our call tomorrow. Researching a bit on how already existing T1w templates were generated (https://www.lead-dbs.org/about-the-mni-spaces/) e.g. MNI152 NLIN 2009, 152 brains were nonlinearly registered into 305 space (i.e. MNI305) and then averaged to create a new template i.e. MNI152 NLIN 2009. So I think this conflicts a bit with the current notion that averaging should take place in a new space defined by the 152 brains and not in an already defined template space, as the MNI152 NLIN 2009 template would otherwise not be a new template, but instead either 1) an atlas tpl-MNI305_atlas-MNI152NLIN2009_T1.nii.gz, or 2) a new template defined in an already existing space tpl-MNI152NLIN2009_space-MNI305_T1w.nii.gz. In the PS13 case, alternatively, this should just be a new template tpl-PS13_pet.nii.gz. But adding the space entity seems necessary to differentiate between different output spaces e.g. fsaverage or MNI305?

It so happens that fsaverage IS MNI305 with an adjustment of an offset in the through-plane (Z) direction :D.

I'm aware of what you mean, however, the difference between MNI305 and MNI152NLin2009cAsym (and variants) is that the alignment into MNI305 is linear, and a new anatomical reference and registration method where employed (nonlinear, since 2006).

Because the registration is nonlinear, I would be confident to call MNI152NLin2009cAsym a new template w.r.t. MNI305.

Let's pick fsaverage, MNI305 and PS13.

PS13 is in fsaverage so long the spatial transform between PS13's maps/surfaces/etc. and fsaverage is identity. However, between MNI305 and fsaverage there is a translation and therefore the transform is not identity.

Between MNI305 and MNI152NLin2009cAsym, the linear part of the transform is identity, but the nonlinear part of the transform (which is not released by MNI because they probably did not even calculate it, I would have not calculated it) is not identity.

Now, I'm going to give you ammo to fire at my argument. Okay, the transform between MNI152NLin2009aAsym, MNI152NLin2009bAsym, MNI152NLin2009cAsym is the identity.

-> Yes, but in this case, I believe we can apply the principle explained above and allow them to be separate. Alternatively, we can change (which is not backward compatible) BIDS' existing designation of some standard spaces so that a, b, and c versions of 2009 become just MNI152NLin2009Asym.

Thanks, @oesteban - I think your take on this is really helpful. For the PS13 example (and other PET examples in general), we generate the average feature map using often a volumetric stream and a surface-based stream. For the volumetric stream, we have used CVS registration (https://surfer.nmr.mgh.harvard.edu/fswiki/mri_cvs_register) estimating and applying a nonlinear registration from subject space to a CVSMNI152 template provided by FreeSurfer. After this registration, the data is averaged across subjects. To me, this aligns with https://www.lead-dbs.org/about-the-mni-spaces/ stating 'MNI152 NLIN 6th generation: Here, the 152 brains were nonlinearly registered into 305 space. Again, only a T1 template is available.', and so this volumetric part should be defined as a new template wrt. the CVSMNI152 template/space (i.e. tpl-PS13_pet.nii.gz). However, for the surface-based stream we estimate and apply the registration from subject space to fsaverage, and then average across subjects. So the spatial transform between this new surface-based feature map and fsaverage is identity, and would not be defined as a new template, and so should instead be defined as a continuous atlas with a _pet.nii.gz extension (i.e. tpl-fsaverage_atlas-PS13_pet.nii.gz'). If one would estimate a parcellation on top of this, the filename would change to tpl-fsaverage_atlas-PS13_dseg/probseg.nii.gz). Right?

I think I would be okay with this, and it would not conflict with prior templateflow work/distribution, but would impact the distribution of templates/atlases moving forward. I guess it might be slightly confusing that the same continuous PET data can be considered both a template and an atlas, and so the alternative would be to use the space entity (as you mentioned above), enforcing that space is present in the filenames if the new template does not generate its own coordinate system. Furthermore, I'd be inclined to still use the space entity in the volumetric stream case above, stating that the PS13 template now exists in CVSMNI152 space, similar to the fact that I think the tpl-MNI152 NLIN 6th generation should theoretically also have had the space-MNI305 part included. Then the PS13 data could be distributed as

tpl-PS13_space-fsaverage_pet.nii.gz
tpl-PS13_space-CVSMNI152_pet.nii.gz
tpl-PS13_space-MNI305_pet.nii.gz
tpl-PS13_space-CVSMNI152_atlas-PS13_dseg.nii.gz

I don't love this deletion, but if it makes the specs clearer, I'm happy to accept.

Besides the label/seg discussion above. This example wants to exactly mean that the brain mask and the head mask WERE NOT projected from a template with those segments defined as part of the AAL atlas. Happy to add this clarification if necessary.

You are losing here the notion that you are still in subject space. Definitely not a use case for atlas.

Please roll back.

I disagree with MAY, this is not optional.

I've reviewed up to this point. I will stop here and let's continue together on a call :)

Thanks for the review, @oesteban. I think a lot of my changes come from my misunderstanding of the intent of the proposal. Looking forward to discussing and clarifying tomorrow.